<?php
//----- 文档块 ----------------------------  
/** 
 * 以 / ** 开头的注释是一个文档块(DocBlock) 
 */  
  
function a0() {}  
  
//----- 文档块描述细节 --------------------  
  
// 文档块包括哪些？  
/** 
 * 文档块按顺序包括3个部分 
 * 1. 短描述 
 * 2. 长描述 
 * 3. tag段 
 */  
  
function a1() {}  
  
//比如  
/** 
 * 短描述 
 * 
 * 这是一个长描述。 
 * 继续长描述。 
 * 如果短描述超过3行，则会只去第一行，作为短描述。 
 * 
 * 另起一段：因为上面的空行 
 */  
  
function a2() {}  
// <p>的例子  
/** 
 * 短描述 
 * 
 * <p>这是一个长描述。 
 * 继续长描述。 
 * 用p标签包围的长描述</p> 
 * <p>另起一段</p> 
 * <p>再另起一段</p> 
 */  
function a3() {}  
  
/** 
 * phpdoc 不支持html的标签，但是可以用下面的几个标签(注意加<>) 
 *  
 * b -- <b> 加粗 </b> 
 * 
 * br -- 换行，<br>可能被某些转换器忽略 <br> 
 * 
 * i -- <i> 斜体 </i> 
 * 
 * kbd -- <kbd> 标示 键盘输入/屏幕输出 </kbd> 
 * 
 * ul -- 没有顺序的列表 
 * 
 * li -- 列表项 
 * 
 * ol -- 顺序列表 
 * 
 * p -- 如果成对使用，则表明一个段，否则只是一个字符串<p> 
 * <p>这是一个段</p> 
 * 
 * pre --  
 * <pre>原样输出，即使是各种标签<b>加粗</b>，相当于XML的CDATA 
 * 注意输出成HTML后，会有效果 
 * </pre> 
 * 
 * var -- 变量名 
 * 
 * samp -- 非php的示例 
 * 
 * <code> 加粗 </code> 
 * 
 * 不要把这些标签想成是字符串，它们应解析器的不同，而被解析成各种形式 
 * 如：b标签在DocBook中是<emphasis>，p标签在PDF中是4个空格 
 * 这些都在模板的options.ini文件中定义 
 * 
 * 要显示带前后尖括号的b标签，可以用《《XXX》》(小写尖括号), 如<<b>> 
 * 
 * 要用@标签，如果行的开头，则用\@，其他地方不需要加反斜杠 \ 
 * 如： 
 * 
 * <code> 
 * \@return abc 
 * 这是一个标签 @name 
 * </code> 
 */   
  
function a4() {}  
  
/** 
 * 简单的列表(不允许嵌套，因为它不再简单) 
 * 
 * 这是一个简单的列表(以-、+、#、o) 
 * - item 1 
 * - item 2, this one 
 *   is multi-line 
 * 这是一个简单的列表(以-、+、#、o) 
 * + item 1 
 * + item 2 
 * 这是一个简单的列表(以-、+、#、o) 
 * # item 1 
 * # item 2 
 * 这是一个简单的列表(以-、+、#、o) 
 * o item 1 
 * o item 2 
 * 列表结束。下面是顺序列表(以数字开头) 
 * 1 ordered item 1 
 * 2 ordered item 2 
 * 列表结束。下面是还是顺序列表(以数字开头，并且有个点) 
 * 1. ordered item 1 
 * 2. ordered item 2 
 */  
function a5() {}  
  
/** 
 * 有嵌套的列表 
 * 
 * 使用ul li ol等标签创建复杂的嵌套列表 
 * <ul> 
 * <li>outer item 1</li> 
 * <li>outer item 2, this one 
 *   is multi-line</li> 
 * <li>item 3 is a nested inner list 
 * <ul> 
 * <li>inner item 1</li> 
 * <li>inner item 2</li> 
 * </ul> 
 * <li>outer item 4</li> 
 * </ul> 
 */  
function a6() {}  
  
/** 
 * 在todo标签中的列表 
 * @todo My Simple TODO List 
 *     - item 1 
 *     - item 2 
 *     - item 3 
 *      - item 3 
 * @todo My Complex TODO List 
 *     <ol> 
 *       <li>item 1.0</li> 
 *       <li>item 2.0</li> 
 *       <li>item 3.0</li> 
 *       <li> 
 *         <ol> 
 *           <li>item 3.1</li> 
 *           <li>item 3.2</li> 
 *         </ol> 
 *       <li> 
 *       <li>item 4.0</li> 
 *     </ol> 
 */  
function a7() {}  
  
//----- Tags ------------------------------------  
  
// Tags：以@开头的标示  
// 下面是常用的Tag  
  
/** 
 * 简单的描述 
 * 
 * 你可以任意扩展描述，成千上万行都可以 
 * 
 * 用 {\@link ellement} 指向一个 element 
 * 比如：指向a1: {@link a1} 
 *  
 * 用 {\@link url} 指向一个站点 
 * 比如：{@link http://www.sina.com.cn 新浪网} 
 *  
 * 用 {\@source} 显示源代码. 
 * 比如：显示函数的代码： 
 * {@source }  
 *  
 * 可用Tag列表: 
 * type 是PHP类型：integer, array, mixed, string等 
 * 
 * - @abstract 
 * - @access       public or private 
 * - @author       作者 <author@email> 
 * - @copyright    版权 
 * - @deprecated   废弃 
 * - @deprec       deprecated的简写 
 * - @example      指向例子 
 * - @exception    兼容javadoc 
 * - @global       type $globalvarname 
 * - @global       type 函数中的全局变量描述 
 * - @ignore 
 * - @internal     给高级程序员看的内部细节描述 
 * - @param        type [$varname] 描述 
 * - @return       type 描述 
 * - @link         URL 
 * - @name         procpagealias [不懂] 
 * - @name         $globalvaralias 
 * - @magic        兼容phpdoc.de 
 * - @package      包名 
 * - @see          指向其他元素的名字，如函数名，类方法等 
 * - @since        一个版本号或日期 
 * - @static 
 * - @staticvar    type 函数中的静态变量的描述 
 * - @subpackage   子包 
 * - @throws       兼容Javadoc 
 * - @todo         待办列表，兼容phpdoc.de 
 * - @var          type    类变量的类型 
 * - @version      版本 
 */  
function if_there_is_an_inline_source_tag_this_must_be_a_function()  
{  
// ...  
}  
  
  
//----- 可以文档的源代码元素 ------------------------------------  
  
//-- 包   
  
/* 
 * Phpdoc划分包的逻辑： 
 * 函数、常量、全局变量属于包 
 * 方法、类变量属于类 
 * 包可以包含多个类 
 * 
 * 一个文件中不要包含多个包 
 */  
  
//--- 程序文件级 --------------------  
/* 
 * 文件的第一个块就是 文件级的文档块(page-level Docblock) 
 * 或者包含@package标签 
 * 它可以有这些元素： 
 *   标准标签 
 *   @package 
 *   @subpackage 
 * 
 */  
  
//--- Include/Require 语句 ----------  
/* 
 * 它可以有这些元素： 
 *   标准标签 
 */   
  
//--- define 语句 -------------------  
/* 
 * 它可以有这些元素： 
 *   标准标签 
 *   @name 
 */   
  
//--- function 声明 -------------------  
/* 
 * 它可以有这些元素： 
 *   标准标签 
 *   @global 
 *   @param 
 *   @return 
 *   @staticvar 
 *   inline {@source} 
 */   
  
//--- 全局变量 ------------------------  
/* 
 * 它可以有这些元素： 
 *   标准标签 
 *   @name 
 */   
  
//--- class 声明 -------------------  
/* 
 * 它可以有这些元素： 
 *   标准标签 
 *   @package 
 *   @subpackage 
 *   @static 
 */   
  
//--- class 变量 -------------------  
/* 
 * 它可以有这些元素： 
 *   标准标签 
 *   @var 
 */   
  
//--- class 变量 -------------------  
/* 
 * 它可以有这些元素： 
 *   标准标签 
 *   @global 
 *   @param 
 *   @return 
 *   @static 
 *   @staticvar 
 *   inline {@source} 
 */   
  
/* 
 * 标准文档标签 
 * 常用的： 
 *   @author 
 *   @copyright 
 *   @version 
 *   @since 
 *   @link 
 *   @see 
 * 其他： 
 *   @tutorial 
 *   @example 
 *   @access 
 *   @deprecated 
 *   @ignore 
 *   @internal 
 *   inline {@internal}} 
 *   inline {@inheritdoc} 
 *   inline {@link} 
 */  
  
/* 
 * 文档标签的继承关系 
 * 
 * Class子类可以继承父类的文档，几个简单的规则： 
 * 
 * @author, @version, @copyright 自动继承，除非显示指明 
 * @package and @subpackage 也会继承，但是建议显示申明，以避免名字冲突 
 * 如果没有简单描述，则会继承 
 * 如果没有长简单描述，则会继承 
 * 如果有长描述，想继承父类的描述，则使用inline标签 {@inheritdoc} 
 */  
  
//----- 命令行参数说明 ------------------------------------  
// phpdoc -h 查看帮助, 参数如下：  
//  
/* -c --config 载入配置文件，如：-c defualt ;载入default.ini文件 
 * -cp --converterparams 动态扩展转换器的参数，多个值用逗号分割 
 * -ct --customtags 自定义tag，多个值用逗号分割；如：-ct mgtag,yourtag  => @mytag @yourtag 
 * -d --directory 指定要解析的目录 
 * -dc --defaultcategoryname 指定默认分类名，默认值为:defaul 
 * -dh --hidden 相当于-dh on，让phpdoc解析以.开头的隐藏文件和目录 
 * -dn --defaultpackagename 指定默认包名，默认是：default 
 * -ed --examplesdir 例子文件寻找路径，如：-ed /full/path/to/example 
 * -f --filename 要解析的源文件名，用,分割，可以使用 * ? 
 * -i --ignore 不解析的文件名或目录，用,分割，可以使用 * ? ； 
 *    - -i  忽略 /path/to/here/tests/* 和 /path/tests/* 
 *    - -i *.inc 忽略所有的 .inc 文件 * 
 *    - -i *path/to/* 忽略 /path/path/to/my/* 和 /path/to/* 
 *    - -i *test* 忽略 /path/tests/* 和 /path/here/my_test.php 
 * -is --ignoresymlinks 忽略任何链接文件，这个只在Linux/Unix下有效，因为Win下没有链接文件 
 * -it --ignore-tags 忽略某些tag；通常用于创建不同版本的文档；如给普通用户的文档，就不需要@todo标签 
 *    忽略inline标签，加上大括号，如--ignore-tags {@internal} 
 *    参数是完整名字，如-it @todo，  -it todo 是错误的写法 
 * -j --javadocdesc 使用javadoc兼容标签 
 * -o --output 指定要使用的转换器和模板；默认可选： 
 *   HTML:frames:* - 输出带框架的HTML页面 
 *     HTML:frames:default - 类Javadoc模板，没有太多格式 
 *     HTML:frames:earthli - Marco von Ballmoos写的模板，非常漂亮 
 *     HTML:frames:l0l33t - 非常漂亮的模板 
 *     HTML:frames:phpdoc.de - 类phpdoc.de's PHPDoc 
 *     HTML:frames:phphtmllib - 非常好的用户发行模板 
 *      以上模板都有javascript增强版本：HTML:frames:DOM/name 其中name表示 default, l0l33t, phpdoc.de, 等等 
 *     HTML:frames:phpedit - 基于PHPEdit帮助生成器 
 * 
 *   HTML:Smarty:* - 输出不带框架的HTML 
 *     HTML:Smarty:default - 用css控制页面布局的模板 
 *     HTML:Smarty:HandS - Layout is based on PHP, but more refined, with logo image 
 *     HTML:Smarty:PHP - Layout is identical to the PHP website 
 * 
 *   CHM:default:* - 输出成CHM格式，需要用Windows的Help软件编译 
 *     CHM:default:default - 基于HTML:frames:l0l33t 
 * 
 *   PDF:default:* - 输出成PDF文档 
 *     PDF:default:default - 标准格式 
 * 
 *   XML:DocBook:* - 输出成XML--DocBook格式 
 *     XML:DocBook/peardoc2:default - pear.php.net（第2版） 
 * 
 * -p --pear Parse a PEAR-style repository (package is directory, _members are @access private) on/off default off  
 * -po --packageoutput output documentation only for selected packages. Use a comma-delimited list  
 * -pp --parseprivate 开启；默认不显示@access private的文档 
 * -q --quiet 关闭多余信息；用法：-q on --不显示  -q off --显示，默认值 
 * -ric --readmeinstallchangelog Specify custom filenames to parse like README, INSTALL or CHANGELOG files  
 * -s --sourcecode generate highlighted sourcecode for every parsed file (PHP 4.3.0+ only) on/off default off  
 * -t --target 要输出的路径 
 * -ti --title 文档的标题 
 * -tb --templatebase 指定自己的模板目录 
 * -ue --undocumentedelements 为没有文档的元素 产生警告; 用法：-ue on  -ue off (默认值) 
 */  
  
/* 
 * phpdoc -t /path/to/output -d path/to/directory1,/another/path,/third/path  
 *   -f /path/to/anotherfile.php -i *test.php,tests/ -pp on -ti My Title -o HTML:frames:phpedit 
 * 
 * phpdoc -c myconfig 
 */  
  
?> 